<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>tablera</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
    <link rel="prev" href="tableng.html" title="tableng" />
    <link rel="next" href="tableseg.html" title="tableseg" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">tablera</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="tableng.html">Prev</a> </td>
          <th width="60%" align="center">Orchestra Opcodes and Operators</th>
          <td width="20%" align="right"> <a accesskey="n" href="tableseg.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="tablera"></a>
      <div class="titlepage"></div>
      <a id="IndexTablera" class="indexterm"></a>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">tablera</span>
        </h2>
        <p>tablera — 
      Reads tables in sequential locations.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp156179328"></a>
        <h2>Description</h2>
        <p>
      These opcode reads tables in sequential locations to an a-rate variable. Some thought is required before using it. It has at least two major, and quite different, applications which are discussed below.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp156180704"></a>
        <h2>Syntax</h2>
        <pre class="synopsis">ares <span class="command"><strong>tablera</strong></span> kfn, kstart, koff</pre>
      </div>
      <div class="refsect1">
        <a id="idp156182912"></a>
        <h2>Performance</h2>
        <p>
      <span class="emphasis"><em>ares</em></span> -- a-rate destination for reading <span class="emphasis"><em>ksmps</em></span> values from a table.
    </p>
        <p>
      <span class="emphasis"><em>kfn</em></span> -- i- or k-rate number of the table to read or write.
    </p>
        <p>
      <span class="emphasis"><em>kstart</em></span> -- Where in table to read or write.
    </p>
        <p>
      <span class="emphasis"><em>koff</em></span> -- i- or k-rate offset into table. Range unlimited - see explanation at end of this section.
    </p>
        <p>
      In one application, <span class="emphasis"><em>tablera</em></span> is intended to be used in pair with <a class="link" href="tablewa.html" title="tablewa"><em class="citetitle">tablewa</em></a>, or with several <span class="emphasis"><em>tablera</em></span> opcodes before a <a class="link" href="tablewa.html" title="tablewa"><em class="citetitle">tablewa</em></a> -- all sharing the same <span class="emphasis"><em>kstart</em></span> variable.
    </p>
        <p>
      These read from and write to sequential locations in a table at audio rates, with <span class="emphasis"><em>ksmps</em></span> floats being written and read each cycle.
    </p>
        <p>
      <span class="emphasis"><em>tablera</em></span> starts reading from location <span class="emphasis"><em>kstart</em></span>. <span class="emphasis"><em>tablewa</em></span> starts writing to location <span class="emphasis"><em>kstart</em></span>, and then writes to <span class="emphasis"><em>kstart</em></span> with the number of the location one more than the one it last wrote. (Note that for <a class="link" href="tablewa.html" title="tablewa"><em class="citetitle">tablewa</em></a>, <span class="emphasis"><em>kstart</em></span> is both an input and output variable.) If the writing index reaches the end of the table, then no further writing occurs and zero is written to <span class="emphasis"><em>kstart</em></span>.
    </p>
        <p>
      For instance, if the table's length was 16 (locations 0 to 15), and <span class="emphasis"><em>ksmps</em></span> was 5. Then the following steps would occur with repetitive runs of the <a class="link" href="tablewa.html" title="tablewa"><em class="citetitle">tablewa</em></a> opcode, assuming that <span class="emphasis"><em>kstart</em></span> started at 0.
    </p>
        <div class="informaltable">
          <table border="1">
            <colgroup>
              <col />
              <col />
              <col />
              <col />
            </colgroup>
            <thead>
              <tr>
                <th>Run Number</th>
                <th>Initial kstart</th>
                <th>Final kstart</th>
                <th>Locations Written</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td>1</td>
                <td>0</td>
                <td>5</td>
                <td>0 1 2 3 4</td>
              </tr>
              <tr>
                <td>2</td>
                <td>5</td>
                <td>10</td>
                <td>5 6 7 8 9</td>
              </tr>
              <tr>
                <td>3</td>
                <td>10</td>
                <td>15</td>
                <td>10 11 12 13 14</td>
              </tr>
              <tr>
                <td>4</td>
                <td>15</td>
                <td>0</td>
                <td>15</td>
              </tr>
            </tbody>
          </table>
        </div>
        <p>
      This is to facilitate processing table data using standard a-rate orchestra code between the <span class="emphasis"><em>tablera</em></span> and <a class="link" href="tablewa.html" title="tablewa"><em class="citetitle">tablewa</em></a>opcodes. They allow all Csound k-rate operators to be used (with caution) on a-rate variables - something that would only be possible otherwise by <span class="emphasis"><em>ksmps</em></span> = 1, downsamp and upsamp.
    </p>
        <div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;">
          <table border="0" summary="Caution: Several cautions">
            <tr>
              <td rowspan="2" align="center" valign="top" width="25">
                <img alt="[Caution]" src="images/caution.png" />
              </td>
              <th align="left">Several cautions</th>
            </tr>
            <tr>
              <td align="left" valign="top">
                <p>
        </p>
                <div class="itemizedlist">
                  <ul class="itemizedlist" style="list-style-type: disc; ">
                    <li class="listitem">
                      <p>
              The k-rate code in the processing loop is really running at a-rate, so time dependent functions like <span class="emphasis"><em>port</em></span> and <span class="emphasis"><em>oscil</em></span> work faster than normal - their code is expecting to be running at k-rate.
            </p>
                    </li>
                    <li class="listitem">
                      <p>
              This system will produce undesirable results unless the <span class="emphasis"><em>ksmps</em></span> fits within the table length. For instance a table of length 16 will accommodate 1 to 16 samples, so this example will work with <span class="emphasis"><em>ksmps</em></span> = 1 to 16.
            </p>
                    </li>
                  </ul>
                </div>
                <p>
      </p>
              </td>
            </tr>
          </table>
        </div>
        <p>
      Both these opcodes generate an error and deactivate the instrument if a table with length &lt; <span class="emphasis"><em>ksmps</em></span> is selected. Likewise an error occurs if <span class="emphasis"><em>kstart</em></span> is below 0 or greater than the highest entry in the table - if <span class="emphasis"><em>kstart</em></span> = table length.
    </p>
        <p>
      </p>
        <div class="itemizedlist">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem">
              <p>
            <span class="emphasis"><em>kstart</em></span> is intended to contain integer values between 0 and (table length - 1). Fractional values above this should not affect operation but do not achieve anything useful.
          </p>
            </li>
            <li class="listitem">
              <p>
            These opcodes are not interpolating, and the <span class="emphasis"><em>kstart</em></span> and <span class="emphasis"><em>koff</em></span> parameters always have a range of 0 to (table length - 1) - not 0 to 1 as is available in other table read/write opcodes. <span class="emphasis"><em>koff</em></span> can be outside this range but it is wrapped around by the final AND operation.
          </p>
            </li>
            <li class="listitem">
              <p>
            These opcodes are permanently in wrap mode. When <span class="emphasis"><em>koff</em></span> is 0, no wrapping needs to occur, since the <span class="emphasis"><em>kstart</em></span>++ index will always be within the table's normal range. <span class="emphasis"><em>koff</em></span> not equal to  0 can lead to wrapping.
          </p>
            </li>
            <li class="listitem">
              <p>
            The offset does not affect the number of read/write cycles performed, or the value written to <span class="emphasis"><em>kstart</em></span> by <a class="link" href="tablewa.html" title="tablewa"><em class="citetitle">tablewa</em></a>.
          </p>
            </li>
            <li class="listitem">
              <p>
            These opcodes cannot read or write the guardpoint. Use <a class="link" href="tablegpw.html" title="tablegpw"><em class="citetitle">tablegpw</em></a> to write the guardpoint after manipulations have been done with <a class="link" href="tablewa.html" title="tablewa"><em class="citetitle">tablewa</em></a>.
          </p>
            </li>
          </ul>
        </div>
        <p>
    </p>
      </div>
      <div class="refsect1">
        <a id="idp156233408"></a>
        <h2>Examples</h2>
        <p>
     </p>
        <div class="informalexample">
          <pre class="programlisting">
kstart   <span class="op">=</span>       0         
                           
<span class="olabel">lab1:</span>
  atemp  <span class="opc">tablera</span> ktabsource, kstart, 0  <span class="comment">; Read 5 values from table into an</span>
         <span class="comment">; a-rate variable.</span> 
                           
  atemp  <span class="op">=</span>       <span class="opc">log</span>(atemp)  <span class="comment">; Process the values using a-rate</span>
         <span class="comment">; code.</span>    

  kstart <span class="opc">tablewa</span> ktabdest, atemp, 0   <span class="comment">; Write it back to the table</span>
         
<span class="octrl">if</span> ktemp  0 <span class="octrl">goto</span> <span class="olabel">lab1</span>      <span class="comment">; Loop until all table locations</span>
         <span class="comment">; have been processed.</span></pre>
        </div>
        <p>
    </p>
        <p>
      The above example shows a processing loop, which runs every k-cycle, reading each location in the table <span class="emphasis"><em>ktabsource</em></span>, and writing the log of those values into the same locations of table <span class="emphasis"><em>ktabdest</em></span>.
    </p>
        <p>
      This enables whole tables, parts of tables (with offsets and different control loops) and data from several tables at once to be manipulated with a-rate code and written back to another (or to the same) table. This is a bit of a fudge, but it is faster than doing it with k-rate table read and write code.
    </p>
        <p>
      Another application is:
    </p>
        <p>
     </p>
        <div class="informalexample">
          <pre class="programlisting">
kzero <span class="op">=</span> 0                    
kloop <span class="op">=</span> 0                    
                                 
kzero <span class="opc">tablewa</span> 23, asignal, 0  <span class="comment">; ksmps a-rate samples written</span>
       <span class="comment">; into locations 0 to (ksmps -1) of table 23.</span>
                                
<span class="olabel">lab1:</span> ktemp <span class="opc">table</span> kloop, 23  <span class="comment">; Start a loop which runs ksmps times,</span>
       <span class="comment">; in which each cycle processes one of</span>
 [ Some code to manipulate ]  <span class="comment">; table 23's values with k-rate orchestra</span>
 [ the value of ktemp. ]  <span class="comment">; code.</span>
                                 
 <span class="opc">tablew</span> ktemp, kloop, 23  <span class="comment">; Write the processed value to the table.</span>
                                
kloop <span class="op">=</span> kloop <span class="op">+</span> 1      <span class="comment">; Increment the kloop, which is both the</span>
       <span class="comment">; pointer into the table and the loop</span>
<span class="octrl">if</span> kloop <span class="op">&lt;</span> ksmps <span class="octrl">goto</span> <span class="olabel">lab1</span>  <span class="comment">; counter. Keep looping until all values</span>
       <span class="comment">; in the table have been processed.</span>
                                
asignal   <span class="opc">tablera</span> 23, 0, 0  <span class="comment">; Copy the table contents back</span>
       <span class="comment">; to an a-rate variable.</span></pre>
        </div>
        <p>
    </p>
        <p>
      <span class="emphasis"><em>koff</em></span> -- This is an offset which is added to the sum of <span class="emphasis"><em>kstart</em></span> and the internal index variable which steps through the table. The result is then ANDed with the lengthmask (000 0111 for a table of length 8 - or 9 with guardpoint) and that final index is used to read or write to the table. <span class="emphasis"><em>koff</em></span> can be any value. It is converted into a long using the ANSI floor() function so that -4.3 becomes -5. This is what we would want when using offsets which range above and below zero.
    </p>
        <p>
      Ideally this would be an optional variable, defaulting to 0, however with the existing Csound orchestra read code, such default parameters must be init time only. We want k-rate here, so we cannot have a default.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp156271888"></a>
        <h2>See Also</h2>
        <p>
      <a class="link" href="tablewa.html" title="tablewa"><em class="citetitle">tablewa</em></a>
    </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="tableng.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="OpcodesTop.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="tableseg.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">tableng </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> tableseg</td>
        </tr>
      </table>
    </div>
  </body>
</html>
